// $Id$
// Licensed under Apache License Version 2.0
// See: http://www.apache.org/licenses/LICENSE-2.0.html
package de.servicezombie.tcmdb.rest.service;

import java.io.InputStream;

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

import de.servicezombie.pub.r1.CommonRestResponse;
import de.servicezombie.tcmdb.rest.vo.WsAuthor;
import de.servicezombie.tcmdb.rest.vo.WsListResult;

/**
 * <b>Examples</b>
 * 
 * <pre>
 *  GET    /testcase-authors/active/all.xml
 *  POST   /testcase-authors/save/ChKa.xml
 *    author={author}...{/author} 
 *  POST   /testcase-authors/save/new.xml
 *    author={author}...{/author}
 * </pre>
 * 
 * <em>author code must be formatted as xml and not as json, but json is easier to document in javadoc</em>
 * 
 * @author ChKa
 * @see WsAuthor
 */
@Path("/testcase-authors")
@Consumes({ "application/json", "application/xml" })
@Produces({ "application/json", "application/xml" })
public interface AuthorService {

	/**
	 * Find all active authors.
	 * 
	 * @response {@link WsListResult} of {@link WsAuthor} in {@link CommonRestResponse}
	 */
	@GET
	@Path("/active/all")
	void getActiveAuthors();

	/**
	 * create a new record or update an existing
	 * 
	 * @param author
	 *            record with new values
	 * @param authorId
	 *            internal id of existing record or 'new' if new record is requested
	 * @response the new created author with all latest fields in database
	 */
	@POST
	@Path("/save/{authorId}")
	void saveAuthor(@PathParam("authorId") String authorId, InputStream input);
}
